NOTE: this man page is inaccurate. It was borrowed from another machine and hasn't been updated to make it correct. #include <sys/types.h> #include <sys/mman.h> mmap(addr, len, prot, share, fd, pos) caddr_t addr; /* starting virt-addr */ int len; /* length (bytes) to map */ int prot; /* RO, RW encoding */ int share; /* private/shared modifications */ int fd; /* open file to be mapped */ off_t pos; /* where in file to begin map */
Fd must reference an open regular (IFREG) or character special (IFCHR) file. The device driver that implements the IFCHR special file must support mapping for this to succeed. Typically, a regular file is used to map shared memory.
The share argument specifies whether modifications to a mapped file are to be kept private to the calling process or shared with other processes accessing the file. If share is MAP_SHARED, all modifications to the file are shared with others who have it concurrently mapped. If share is MAP_PRIVATE, all modifications are local to the calling process; this doesn't restrict other processes from mapping the file. MAP_SHARED and MAP_PRIVATE have no relation to flock(2), and do not restrict read and write system-calls. If share is MAP_ZEROFILL, the space indicated from addr for len bytes is replaced by private pages that are zero-filled when referenced. MAP_ZEROFILL ignores the fd argument, and pos is ignored other than being checked for alignment (specifying fd and pos = 0 is recommended).
The prot argument should be PROT_WRITE for write access to the mapped region, PROT_READ for read access, PROT_EXEC for executable access. These values can be ORed to obtain read-write access, etc. For programming convenience, PROT_RDWR is defined as (PROT_READ|PROT_WRITE). The file access permissions on fd must allow the requested access. The prot argument affects only the calling process; other processes mapping the same file may have different access.
The addr, len, and pos arguments must be integral multiples of the system page size, as defined by getpagesize(2). It is possible to map over previously mapped pages. If addr and len specify a nonexistent part of the process's address space, the process's data segment is grown to accommodate the request, and the process ``break'' (see brk(2)) is set to the high end of the mapped region. Reference to any ``holes'' between the mapped region and the rest of the data segment result in a segmentation fault (SIGSEGV). mmap does not allow mapping over text or stack pages.
When memory is mapped to a regular file, the file acts like a paging area for the mapped memory region. Read and write operations to mapped regions of the file also affect the corresponding memory. The memory contents are copied out to the file when the process is swapped or when it exits, or when the region is otherwise unmapped by the last process that has it mapped. For programs that use shared memory but do not need a permanent disk image of the memory, the file associated with fd can be unlinked (see unlink(2)) even before the call to mmap: if the file is unlinked when the region is unmapped, the disk space will not be updated.
Regular files have their size rounded up to a file-system block boundary. Any non-existent space in the file at the time of the mmap request (for example, in a sparse file) is allocated, and filled with zeroes when referenced. Both of these operations require write access to the file.
The type of file referenced may impose further restrictions on the pos, offset, or other parameters. Refer to the manual entry of the relevant device driver (for example, pmap(4)) for details.
Closing a file descriptor previously used in an mmap operation unmaps all pages mapped by that file descriptor (see also munmap(2)). (Note: this may change in order to provide compatibility with sunOS.) If the file-descriptor has been duped prior to being closed, no unmap takes place.
Mmap can be called multiple times with the same file descriptor, resulting in several (possibly overlapping) mapped regions. A process can have up to 8 regions mapped simultaneously; mappings that are completely overlapped by subsequent mappings are not counted in this total. Mappings which use the same file descriptor, and addr and pos arguments which align virtually with a previous mapping, also don't count in this total; the simplest case is mapping more of a file, starting from the end of a previous mapping.
All mapped files remain mapped in both the parent and child process after a fork. All flavors of the exec and exit system calls, when successful, remove all maps the calling process had established. If a process has any maps, vfork behaves exactly like fork. A child of a vfork that has not yet execed a new image cannot successfully execute mmap.
There are three types of mapping: paged, physical, and non-paged memory. The type of mapping is determined by the type of file being mapped. Paged maps support shared memories and mapped regular files. Physical maps deal with hardware that has restrictive access capability (for example, the MULTIBUS address space, including Atomic Lock Memory). Non-paged memory maps are typically used for special reserved areas of system memory; they are assumed to behave exactly like memory, supporting accesses of arbitrary size and alignment, DMA, etc.
System services (raw IO, read/write, stat, etc.) are supported in paged and non-paged memory maps; attempts at such services in physically mapped address space result in an error, typically EFAULT. Core dumps include a copy of any mapped address space; however, physically mapped addresses read as zero.
Regular files (IFREG) are always page-mapped. Character special files (IFCHR) can support paged, physical, or non-paged maps, depending on the underlying hardware. Physical and non-paged maps are always valid in the process address space; references won't cause a page fault.
When mmap increases a program's address space, it also attempts to increase its allowable resident set size.
The following code maps the first page of Atomic Lock Memory into the process's virtual address space at address 0x200000. This region will be shared with the process's children and with any other process that maps the file ``/dev/alm/alm00''. pgsz = getpagesize(); fd = open ("/dev/alm/alm00", O_RDWR, 0); mmap (0x200000, pgsz, PROT_RDWR, MAP_SHARED, fd, 0);
If a file is extended to a file-system block boundary, its original size is lost.
Current restrictions on what parts of the address space can be re-mapped should be lifted.
To minimize overhead, mapped regions should be kept as close as possible to the low end of process memory.
Address space holes under the process ``break'' read as zeroes in core files.